TypeScript execution environment and REPL for node.js, with source map support
The ts-node npm package is a TypeScript execution engine and REPL for Node.js. It allows developers to run TypeScript files directly without precompiling them to JavaScript. This is particularly useful for development purposes where you can execute scripts or run a REPL environment without an additional build step.
Execute TypeScript files
Run a TypeScript file directly from the command line without prior compilation.
ts-node script.tsREPL
Start a TypeScript REPL (Read-Eval-Print Loop) to execute TypeScript code interactively.
ts-nodeTranspile Only Mode
Run TypeScript files without type checking for faster execution, suitable for development.
ts-node --transpile-only script.tsType Checking
Enable type checking when running a TypeScript file, ensuring that the code adheres to the defined types.
ts-node --type-check script.tsIntegration with Testing Frameworks
Use ts-node to run TypeScript tests with Mocha or other Node.js testing frameworks.
mocha --require ts-node/register tests/**/*.spec.tsesbuild-register uses the esbuild bundler to transpile TypeScript and JavaScript files on the fly. It is known for its speed and efficiency compared to ts-node, which can be slower due to its full type checking.
babel-node is a part of the Babel toolchain that allows running TypeScript and modern JavaScript directly. It is similar to ts-node but uses Babel for transpilation, which can be more configurable and supports a wider range of JavaScript features and experimental syntax.
sucrase-node is a development tool that allows super-fast development builds. It is similar to ts-node but focuses on speed by avoiding full type checking and supporting a subset of TypeScript features.
swc-node is a TypeScript/JavaScript compiler that uses SWC, a super-fast compiler written in Rust. It is designed to be a faster alternative to ts-node, especially for larger codebases.
TypeScript execution and REPL for node.js, with source map support. Works with
typescript@>=2.7.
Native ESM support is currently experimental. For usage, limitations, and to provide feedback, see #1007.
# Locally in your project.
npm install -D typescript
npm install -D ts-node
# Or globally with TypeScript.
npm install -g typescript
npm install -g ts-node
Tip: Installing modules locally allows you to control and share the versions through package.json. TS Node will always resolve the compiler from cwd before checking relative to its own installation.
# Execute a script as `node` + `tsc`.
ts-node script.ts
# Starts a TypeScript REPL.
ts-node
# Execute code with TypeScript.
ts-node -e 'console.log("Hello, world!")'
# Execute, and print, code with TypeScript.
ts-node -p -e '"Hello, world!"'
# Pipe scripts to execute with TypeScript.
echo 'console.log("Hello, world!")' | ts-node
# Equivalent to ts-node --script-mode
ts-node-script scripts.ts
# Equivalent to ts-node --transpile-only
ts-node-transpile-only scripts.ts
#!/usr/bin/env ts-node-script
console.log("Hello, world!")
ts-node-script is recommended because it enables --script-mode, discovering tsconfig.json relative to the script's location instead of process.cwd(). This makes scripts more portable.
Passing CLI arguments via shebang is allowed on Mac but not Linux. For example, the following will fail on Linux:
#!/usr/bin/env ts-node --script-mode --transpile-only --files
// This shebang is not portable. It only works on Mac
You can require ts-node and register the loader for future requires by using require('ts-node').register({ /* options */ }). You can also use file shortcuts - node -r ts-node/register or node -r ts-node/register/transpile-only - depending on your preferences.
Note: If you need to use advanced node.js CLI arguments (e.g. --inspect), use them with node -r ts-node/register instead of the ts-node CLI.
TS Node exports a create() function that can be used to initialize a TypeScript compiler that isn't registered to require.extensions, and it uses the same code as register.
Mocha 6
mocha --require ts-node/register --watch-extensions ts,tsx "test/**/*.{ts,tsx}" [...args]
Note: --watch-extensions is only used in --watch mode.
Mocha 7
mocha --require ts-node/register --extensions ts,tsx --watch --watch-files src 'tests/**/*.{ts,tsx}' [...args]
ts-node node_modules/tape/bin/tape [...args]
# Create a `gulpfile.ts` and run `gulp`.
gulp
Create a new node.js configuration, add -r ts-node/register to node args and move the program to the args list (so VS Code doesn't look for outFiles).
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"runtimeArgs": [
"-r",
"ts-node/register"
],
"args": [
"${workspaceFolder}/index.ts"
]
}
Note: If you are using the --project <tsconfig.json> command line argument as per the Configuration Options, and want to apply this same behavior when launching in VS Code, add an "env" key into the launch configuration: "env": { "TS_NODE_PROJECT": "<tsconfig.json>" }.
Create a new Node.js configuration and add -r ts-node/register to "Node parameters."
Note: If you are using the --project <tsconfig.json> command line argument as per the Configuration Options, and want to apply this same behavior when launching in IntelliJ, specify under "Environment Variables": TS_NODE_PROJECT=<tsconfig.json>.
TypeScript Node works by registering the TypeScript compiler for .tsx? and .jsx? (when allowJs == true) extensions. When node.js has an extension registered (via require.extensions), it will use the extension internally for module resolution. When an extension is unknown to node.js, it handles the file as .js (JavaScript). By default, TypeScript Node avoids compiling files in /node_modules/ for three reasons:
P.S. This means if you don't register an extension, it is compiled as JavaScript. When ts-node is used with allowJs, JavaScript files are transpiled using the TypeScript compiler.
tsconfig.jsonTypescript Node loads tsconfig.json automatically. Use --skip-project to skip loading the tsconfig.json.
It is resolved relative to --dir using the same search behavior as tsc. In --script-mode, this is the directory containing the script. Otherwise it is resolved relative to process.cwd(), which matches the behavior of tsc.
Use --project to specify the path to your tsconfig.json, ignoring --dir.
Tip: You can use ts-node together with tsconfig-paths to load modules according to the paths section in tsconfig.json.
You can set options by passing them before the script path, via programmatic usage, via tsconfig.json, or via environment variables.
ts-node --compiler ntypescript --project src/tsconfig.json hello-world.ts
Note: ntypescript is an example of a TypeScript-compatible compiler.
ts-node supports --print (-p), --eval (-e), --require (-r) and --interactive (-i) similar to the node.js CLI options.
-h, --help Prints the help text-v, --version Prints the version. -vv prints node and typescript compiler versions, too-s, --script-mode Resolve config relative to the directory of the passed script instead of the current directory. Changes default of --dirThe name of the environment variable and the option's default value are denoted in parentheses.
-T, --transpile-only Use TypeScript's faster transpileModule (TS_NODE_TRANSPILE_ONLY, default: false)-H, --compiler-host Use TypeScript's compiler host API (TS_NODE_COMPILER_HOST, default: false)-I, --ignore [pattern] Override the path patterns to skip compilation (TS_NODE_IGNORE, default: /node_modules/)-P, --project [path] Path to TypeScript JSON project file (TS_NODE_PROJECT)-C, --compiler [name] Specify a custom TypeScript compiler (TS_NODE_COMPILER, default: typescript)-D, --ignore-diagnostics [code] Ignore TypeScript warnings by diagnostic code (TS_NODE_IGNORE_DIAGNOSTICS)-O, --compiler-options [opts] JSON object to merge with compiler options (TS_NODE_COMPILER_OPTIONS)--dir Specify working directory for config resolution (TS_NODE_CWD, default: process.cwd(), or dirname(scriptPath) if --script-mode)--scope Scope compiler to files within cwd (TS_NODE_SCOPE, default: false)--files Load files, include and exclude from tsconfig.json on startup (TS_NODE_FILES, default: false)--pretty Use pretty diagnostic formatter (TS_NODE_PRETTY, default: false)--skip-project Skip project config resolution and loading (TS_NODE_SKIP_PROJECT, default: false)--skip-ignore Skip ignore checks (TS_NODE_SKIP_IGNORE, default: false)--emit Emit output files into .ts-node directory (TS_NODE_EMIT, default: false)--prefer-ts-exts Re-order file extensions so that TypeScript imports are preferred (TS_NODE_PREFER_TS_EXTS, default: false)--log-error Logs TypeScript errors to stderr instead of throwing exceptions (TS_NODE_LOG_ERROR, default: false)transformers _ts.CustomTransformers | ((p: _ts.Program) => _ts.CustomTransformers): An object with transformers or a function that accepts a program and returns an transformers object to pass to TypeScript. Function isn't available with transpileOnly flagreadFile: Custom TypeScript-compatible file reading functionfileExists: Custom TypeScript-compatible file existence functionMost options can be specified by a "ts-node" object in tsconfig.json using their programmatic, camelCase names. For example, to enable --transpile-only:
// tsconfig.json
{
"ts-node": {
"transpileOnly": true
},
"compilerOptions": {}
}
Our bundled JSON schema lists all compatible options.
Any error that is not a TSError is from node.js (e.g. SyntaxError), and cannot be fixed by TypeScript or ts-node. These are runtime issues with your code.
Current node.js stable releases do not support ES modules. Additionally, ts-node does not have the required hooks into node.js to support ES modules. You will need to set "module": "commonjs" in your tsconfig.json for your code to work.
TypeScript Node does not use files, include or exclude, by default. This is because a large majority projects do not use all of the files in a project directory (e.g. Gulpfile.ts, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. ts-node index.ts) and TypeScript resolves dependencies based on imports and references.
For global definitions, you can use the typeRoots compiler option. This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the TypeScript Handbook.
Example tsconfig.json:
{
"compilerOptions": {
"typeRoots" : ["./node_modules/@types", "./typings"]
}
}
Example project structure:
<project_root>/
-- tsconfig.json
-- typings/
-- <module_name>/
-- index.d.ts
Example module declaration file:
declare module '<module_name>' {
// module definitions go here
}
For module definitions, you can use paths:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"custom-module-type": ["types/custom-module-type"]
}
}
}
An alternative approach for definitions of third-party libraries are triple-slash directives. This may be helpful if you prefer not to change your TypeScript compilerOptions or structure your custom type definitions when using typeRoots. Below is an example of the triple-slash directive as a relative path within your project:
/// <reference types="./types/untyped_js_lib" />
import UntypedJsLib from "untyped_js_lib"
Tip: If you must use files, include, or exclude, enable --files flags or set TS_NODE_FILES=true.
TypeScript Node compiles source code via require(), watching files and code reloads are out of scope for the project. If you want to restart the ts-node process on file change, existing node.js tools such as nodemon, onchange and node-dev work.
There's also ts-node-dev, a modified version of node-dev using ts-node for compilation and won't restart the process on file change.
MIT
FAQs
TypeScript execution environment and REPL for node.js, with source map support
The npm package ts-node receives a total of 24,746,929 weekly downloads. As such, ts-node popularity was classified as popular.
We found that ts-node demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.